inbox/Using Acsis Architecture MCP Server in Claude Code.md

Using Acsis Architecture MCP Server in Claude Code

Setup Instructions

1. Locate Your Claude Code Config File

Claude Code stores its configuration in:

~/.config/claude/config.json

2. Add the MCP Server Configuration

Edit the config file to add the MCP server. Here's the configuration to add:

{
  "mcpServers": {
    "acsis-architecture": {
      "command": "python3",
      "args": [
        "/Users/dcastonguay/source/acsis/portfolio/acsis-core/development/resources/acsis-architecture-dxt/server/simple_main.py",
        "--acsis-root=/Users/dcastonguay/source/acsis/portfolio/acsis-core",
        "--debug=false",
        "--skip-schema=false"
      ],
      "env": {}
    }
  }
}

If you already have other MCP servers configured, add it to the existing mcpServers object:

{
  "mcpServers": {
    "existing-server": { ... },
    "acsis-architecture": {
      "command": "python3",
      "args": [
        "/Users/dcastonguay/source/acsis/portfolio/acsis-core/development/resources/acsis-architecture-dxt/server/simple_main.py",
        "--acsis-root=/Users/dcastonguay/source/acsis/portfolio/acsis-core",
        "--debug=false",
        "--skip-schema=false"
      ],
      "env": {}
    }
  }
}

3. Configuration Options

You can adjust the following parameters:

--debug=true - Enable debug logging for troubleshooting
--skip-schema=true - Skip database schema analysis for faster startup
--acsis-root=/path/to/repo - Point to your Acsis repository location

4. Restart Claude Code

After updating the configuration, restart Claude Code for the changes to take effect:

# Kill any existing Claude Code processes
pkill -f "claude code"

# Start Claude Code again
claude

5. Verify the MCP Server is Running

Once Claude Code starts, you should see the MCP tools available. You can test by asking Claude to:

"Use the MCP tools to list all Acsis components"
"Search for endpoints related to assets"
"Get the component info for core-data"

Alternative: Command Line Testing

You can also test the MCP server directly from the command line:

cd /Users/dcastonguay/source/acsis/portfolio/acsis-core/development/resources/acsis-architecture-dxt

# Test with JSON-RPC commands
echo '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' | python3 server/simple_main.py --acsis-root=/Users/dcastonguay/source/acsis/portfolio/acsis-core

# List available tools
echo '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}' | python3 server/simple_main.py --acsis-root=/Users/dcastonguay/source/acsis/portfolio/acsis-core

Available MCP Tools

Once configured, you'll have access to these tools in Claude Code:

Component Tools

list_components - List all Acsis components
get_component_info - Get detailed info about a component
search_components - Search components by functionality
get_component_dependencies - Show component dependencies
get_aspire_configuration - Get .NET Aspire orchestration config

API Tools

get_openapi_spec - Get OpenAPI spec for a component
search_endpoints - Search for API endpoints
get_endpoint_details - Get detailed endpoint information
get_api_models - Get API models for a component

Schema Tools

get_database_schema - Get database schema for a component
search_entities - Search for database entities
get_entity_relationships - Get entity relationship information

Troubleshooting

Server Not Starting

Check the Python path: Make sure python3 is available
Verify the script path exists
Check repository path is correct
Look at Claude Code logs for errors

Tools Not Available

Restart Claude Code after config changes
Verify the JSON syntax in config.json
Check that the MCP server starts successfully

Performance Issues

Use --skip-schema=true to skip database analysis
Enable --debug=true to see what's taking time
Check that OpenAPI specs are generated in your components

Example Usage in Claude Code

Once configured, you can use the MCP tools naturally in your conversations:

You: "What components are available in the Acsis architecture?"
Claude: Let me check the available components using the MCP tools...
[Uses list_components tool]

You: "Show me all the API endpoints in the identity component"
Claude: I'll search for the identity component's endpoints...
[Uses get_openapi_spec tool]

You: "What database entities does core-data manage?"
Claude: Let me examine the core-data database schema...
[Uses get_database_schema tool]

The MCP server provides semantic understanding of your entire Acsis architecture, making Claude Code much more intelligent about your codebase!

Documentation